home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / uw201.zip / UW_HELP6.HLP < prev    next >
Text File  |  1991-10-07  |  16KB  |  397 lines
  1. `co(4,7);────────────────────────── /// Print Support ───────────────────────────────`co();
  2.  
  3.                                `keyword(Introduction,/// Introduction);
  4.                            `keyword(Key Structure Elements,/// Key Structure Elements);
  5.  
  6. ┌──────────────────────────────────────────────────────────────────────────┐    
  7. │               `keyword(init_printer,/// init_printer);                `keyword(end_printer,/// end_printer);                    │
  8. │               `keyword(print_char,/// print_char);                  `keyword(print_data,/// print_data);                     │
  9. │               `keyword(print_eol,/// print_eol);                   `keyword(print_file,/// print_file);                     │
  10. │               `keyword(print_screen,/// print_screen);                `keyword(print_str,/// print_str);                      │
  11. │               `keyword(print_window,/// print_window);                `keyword(realloc_printer,/// realloc_printer);                │
  12. │               `keyword(set_prt_xlat,/// set_prt_xlat);                `keyword(print_in_bkgrnd,/// print_in_bkgrnd);                │
  13. └──────────────────────────────────────────────────────────────────────────┘
  14.  
  15. `color(RED,LIGHTGRAY);───────────────────────── /// Introduction ─────────────────────────────────`color();
  16.  
  17.   These routines are primarily designed for printing to a PRINTER.       
  18.   However, any DOS file/device can be "printed" to. (com1,lpt1,tmp.dat,etc)
  19.   The queuing routines are unique in the fact that the can "dynamically" 
  20.   reallocate themselves and "grow" and "shrink" on the fly without losing
  21.   a single byte of data.  The reallocation routines take advantage of the
  22.   lightning fast movmem, as much out of convenience as speed.  An 8Mhz   
  23.   286 can que 25,000 bytes worth of text strings, reallocating every     
  24.   2048 bytes in ~1 second; really quite remarkable.                      
  25.   The output is also quite fast if the "block mode" is taken advantage   
  26.   of.  Even when block mode is not used, and a "write" occurs every byte,
  27.   ~1024 bytes can be "printed" per second on the same machine.  Not many 
  28.   printers can keep up with this!  This is sped up in block mode by      
  29.   writing up to 512 bytes at a time.  This is not done by default since  
  30.   outputting to a comm port at a slow baud rate may hamper performance,  
  31.   especially if many bytes are written at once.                          
  32.   As many as four print queues can be active and printing concurrently!
  33.  
  34. `color(RED,LIGHTGRAY);────────────────────── /// /// Key Structure Elements ─────────────────────────────`color();
  35.  
  36.   Several print structure elements are of importance.
  37.     "halt" controls output from the queue.  If 1, output stops and the data
  38.   in the queue remains unmodified.  If 0, output continues.
  39.     "block_mode" controls the number of bytes output per call to the
  40.   function "print_in_bkgnd".  If 0, only one byte per call will be output.
  41.   This is useful for communication devices or printers.  If outputting to
  42.   a file or laser printer, setting block mode to 1 will allow up to
  43.   128 bytes to be output per call, thereby increasing performance.
  44.     "xlat" and "xlat_flag" control printer translation.  See `keyword(set_prt_xlat,/// set_prt_xlat);
  45.   for more details.  These variables can be modified directly if desired.
  46.  
  47. `co(10,1);/// init_printer`co();   `keyword(source,[UW_PRINT.C]~init_printer);
  48.   This routine initializes a printer queue.  Printer queues can be either
  49.   ram-based or disk-based. If ram-based, a queue can be no greater than 
  50.   64k.  Disk-based queues can be up to 2 gigabytes. (Though we have never
  51.   actually tried this!).  If disk-based, the initial and maximum size
  52.   should be set to the same value, and a second filename is used as a
  53.   disk buffer.  Be sure that the isize and msize values are "long".
  54.   If any error occurs (file cannot be open, memory cannot be allocated,etc)
  55.   a 0 will be returned.
  56.  
  57. Prototype:
  58. int init_printer( char *fname, char *diskbuff,
  59.   long isize, long msize, PRINT *p );
  60.  
  61. Parameters:
  62. `co(11,1);    char  *fname`co();
  63.         A pointer to a string containing the filename/device to print to.
  64. `co(11,1);    char  *diskbuff`co();
  65.         A pointer to a string containing the filename/device to use as a disk
  66.     buffer.  This is NULL for ram-based queues.
  67. `co(11,1);    long  isize`co();
  68.         The initial size of the print queue. (Maximum 64k if ram based)
  69. `co(11,1);    long  msize`co();
  70.         The maximum size of the print queue. (Maximum 64k if ram based)
  71.         isize and msize should be set equal if using a disk based queue.
  72. `co(11,1);    PRINT *p`co();
  73.     A pointer to a print queue structure.   
  74.  
  75. Usage:
  76.     PRINT printer1, printer2;
  77.     ...
  78.     if( !init_printer("out1.prt", NULL, 2048L, 16384L, &printer1) )
  79.         wn_plst(0,0,"cannot initialize printer", wnp);
  80.     if( !init_printer("out2.prt", "disk.buf", 32768L, 32768L, &printer2) )
  81.         wn_plst(0,0,"cannot initialize printer", wnp);
  82.  
  83. `co(10,1);/// end_printer`co();   `keyword(source,[UW_PRINT.C]~end_printer);
  84.   This routine closes any files and frees any memory used by the print
  85.     queue.  If disk-based, the temporary disk file is left intact so that
  86.     it will not have to be recreated during the next program execution.
  87.     You may delete this file yourself if desired.
  88.  
  89. Prototype:
  90. int end_printer( PRINT *p );
  91.  
  92. Parameters:
  93. `co(11,1);    PRINT *p`co();
  94.     A pointer to a print queue structure.   
  95.  
  96. Usage:
  97.     PRINT printer1;
  98.     ...
  99.     end_printer(&printer1);
  100.  
  101. `co(10,1);/// print_char`co();   `keyword(source,[UW_PRINT.C]~print_char);
  102.   This routine prints a single character. A 0 is returned if an error occurs.
  103.  
  104. Prototype:
  105. int print_char( uchar c, PRINT *p );
  106.  
  107. Parameters:
  108. `co(11,1);    uchar c`co();
  109.     A single byte to queue for printing.   
  110. `co(11,1);    PRINT *p`co();
  111.     A pointer to a print queue structure.   
  112.  
  113. Usage:
  114.     PRINT printer1;
  115.     ...
  116.     print_char('\r', &printer1);
  117.  
  118. `co(10,1);/// print_data`co();   `keyword(source,[UW_PRINT.C]~print_data);
  119.   This routine prints a block of data. A 0 is returned if an error occurs.
  120.  
  121. Prototype:
  122. int print_data( uchar *data, int cnt, PRINT *p );
  123.  
  124. Parameters:
  125. `co(11,1);    uchar *data`co();
  126.     A pointer to the data to queue for printing.   
  127. `co(11,1);    int   cnt`co();
  128.     The number of bytes to print.   
  129. `co(11,1);    PRINT *p`co();
  130.     A pointer to a print queue structure.   
  131.  
  132. Usage:
  133.     uchar data[132];
  134.     PRINT printer1;
  135.     ...
  136.     print_data(data, 132, &printer1);
  137.  
  138. `co(10,1);/// print_eol`co();   `keyword(source,[UW_PRINT.C]~print_eol);
  139.   This routine prints an end-of-line sequence. The print structure contains
  140.   tow variables, "cr_cnt" and "lf_cnt" that control this sequence.  For
  141.   every carriage return "cr_cnt", "lf_cnt" line feeds are output.  For
  142.   instance, the simple case of cr_cnt = lf_cnt = 1 outputs \r\n  while
  143.   cr_cnt = 1, lf_cnt = 2 outputs \r\n\n. A 0 is returned if an error occurs.
  144.  
  145. Prototype:
  146. int print_eol( PRINT *p );
  147.  
  148. Parameters:
  149. `co(11,1);    PRINT *p`co();
  150.     A pointer to a print queue structure.   
  151.  
  152. Usage:
  153.     PRINT printer1;
  154.     ...
  155.     print_eol(&printer1);
  156.  
  157. `co(10,1);/// print_file`co();   `keyword(source,[UW_PRINT.C]~print_file);
  158.   This routine prints an entire file.  The file is queued in "raw" format,
  159.   no CR/LF translation occurs.  Make sure that there is enough room in the
  160.   queue to hold the entire file.  A 0 is returned if an error occurs.
  161.  
  162. Prototype:
  163. int print_file( char *fname, PRINT *p );
  164.  
  165. Parameters:
  166. `co(11,1);    char  *fname`co();
  167.         A pointer to a string containing the filename/device to print to.
  168. `co(11,1);    PRINT *p`co();
  169.     A pointer to a print queue structure.   
  170.  
  171. Usage:
  172.     PRINT printer1;
  173.     ...
  174.     print_file("uw_help6.hlp", &printer1);
  175.  
  176. `co(10,1);/// print_screen`co();   `keyword(source,[UW_PRINT.C]~print_screen);
  177.   This routine prints the contents of the entire screen.  A 0 is returned if
  178.     an error occurs.
  179.  
  180. Prototype:
  181. int print_screen( PRINT *p );
  182.  
  183. Parameters:
  184. `co(11,1);    PRINT *p`co();
  185.     A pointer to a print queue structure.   
  186.  
  187. Usage:
  188.     PRINT printer1;
  189.     ...
  190.     print_screen(&printer1);
  191.  
  192. `co(10,1);/// print_str`co();   `keyword(source,[UW_PRINT.C]~print_str);
  193.   This routine prints a single NULL terminated string. A 0 is returned if
  194.     an error occurs.
  195.  
  196. Prototype:
  197. int print_str( uchar *str, PRINT *p );
  198.  
  199. Parameters:
  200. `co(11,1);    char  *str`co();
  201.         A pointer to the string to print.
  202. `co(11,1);    PRINT *p`co();
  203.     A pointer to a print queue structure.   
  204.  
  205. Usage:
  206.     PRINT printer1;
  207.     ...
  208.     print_string("This is a print string", &printer1);
  209.  
  210. `co(10,1);/// print_window`co();   `keyword(source,[UW_PRINT.C]~print_window);
  211.   This routine prints the contents of the current window.  If the window
  212.     is bordered and the window parameter "inside" is 1, only the inside of
  213.     the window is printed.  If "inside" is 0, the entire window, including
  214.     the border is printed.  A 0 is returned if an error occurs.
  215.   Note that this works even if the window is overlapped!
  216.  
  217. Prototype:
  218. int print_window( WINDOW *wnp, PRINT *p );
  219.  
  220. Parameters:
  221. `co(11,1);    WINDOW *wnp`co();
  222.         A pointer to the window to print.
  223. `co(11,1);    PRINT  *p`co();
  224.     A pointer to a print queue structure.   
  225.  
  226. Usage:
  227.     PRINT printer1;
  228.     WINDOW wn;
  229.     ...
  230.     print_window(&wn, &printer1);
  231.  
  232. `co(10,1);/// realloc_printer`co();   `keyword(source,[UW_PRINT.C]~realloc_printer);
  233.   This routine is an internal routine and is used to "grow" and "shrink"
  234.     ram-based printer queues dynamically.  A 0 is returned if an error occurs.
  235.  
  236. Prototype:
  237. int realloc_printer( long new_size, PRINT *p );
  238.  
  239. Parameters:
  240. `co(11,1);    long new_size`co();
  241.         The new size, either greater or less than the current size.
  242. `co(11,1);    PRINT  *p`co();
  243.     A pointer to a print queue structure.   
  244.  
  245. Usage:
  246.     PRINT printer1;
  247.     ...
  248.     realloc_printer(32000L, &printer1);
  249.  
  250. `co(10,1);/// set_prt_xlat`co();   `keyword(source,[UW_PRINT.C]~set_prt_xlat);
  251.   This routine allows translation of the data to occur.  For instance, the
  252.     ASCII data queued can be printed as EBCDIC by pointing this to the
  253.   appropriate table.  Another example would be to point to a table that
  254.   contained ASCII equivalents to the IBM extended characters, thereby
  255.   providing support for older printers that do not support them.
  256.   Note that the translation occurs during output, not during the queueing
  257.   process.
  258.  
  259. Prototype:
  260. void set_prt_xlat( int state, uchar *xlat, PRINT *p );
  261.  
  262. Parameters:
  263. `co(11,1);    int   state`co();
  264.         If 1, the translation table is activated, if 0 it is deactivated.
  265. `co(11,1);    uchar *xlat`co();
  266.         A pointer to the translation table.
  267. `co(11,1);    PRINT  *p`co();
  268.     A pointer to a print queue structure.   
  269.  
  270. Usage:
  271.     uchar xlat[256];
  272.     PRINT printer1;
  273.     ...
  274.     set_prt_xlat(1, xlat, &printer1);
  275.  
  276. `co(10,1);/// print_in_bkgrnd`co();   `keyword(source,[UW_PRINT.C]~print_in_bkgrnd);
  277.   This routine is the "heart" of the printer routines.  It actually scans
  278.     the printer queues and outputs the data to the appropriate file/device.
  279.   You can call this routine as often and as fast as you see fit, or let
  280.   the idle function call it in the "background".  There are no requirements
  281.   as to when or how often this routine is called, but the more frequent
  282.   the better the printer performance.  The total number of bytes output
  283.   is returned.
  284.  
  285. Prototype:
  286. int print_in_bkgrnd( void );
  287.  
  288. Parameters:
  289.  
  290. Usage:
  291.     ...
  292.     while( !kbhit() )
  293.         print_in_bkgrnd();
  294. OR
  295.     set_idle_func(print_in_bkgrnd);                /* wait event will call this for us */
  296.     do{
  297.             ...
  298.   }while(!end);
  299.  
  300. `co(4,7);─────────────────────── /// Timer/Sound Support ────────────────────────────`co();
  301.  
  302.   UltraWin V2.0 has the additional capability of "taking over" the PC timer
  303.   interrupt.  It does this in a friendly manner by calling the old timer
  304.   vector at the proper rate.  However, it is `co(15,?);very important`co(); to remember
  305.   to call the function `co(11,1);end_video()`co(); before exiting your program or
  306.   you may experience strange "crashes".  In addition, UltraWin increased
  307.   the timer interrupt rate by a factor of 5, or approximately 91 ticks per
  308.   second.  This allows you much finer control over your programs.  We also
  309.   provide you with an easy to use timer facility for taking advantage of
  310.   these features.  UltraWin also allows you to sound the PC speaker at a
  311.   given frequency for a certain amount of time and the timer interrupt will
  312.   turn the speaker off for you.
  313.  
  314.   The function `co(11,1);end_video()`co(); calls `co(11,1);end_clock()`co(); to restore the vector and
  315.   clock rate if you forget to make the call. Taking over the PC timer will
  316.   not affect the PC clock as the original interrupt is still called 18.2
  317.   times per second.  However, if your program or another program that 
  318.   controls your program also takes over the clock and changes the rate you
  319.   may experience some problems.  If this is the case, simply do not call
  320.   `co(11,1);init_clock()`co();.  You will not be able to use the timer variables or
  321.   call `co(11,1);tone()`co(); but `co(11,1);wait_ticks()`co(); will still operate normally.
  322.   
  323.   There are 4 seperate countdown timers available for use in your programs.
  324.   These are simply global variables that are decremented to 0 by the timer
  325.   interrupt.  For instance, to delay for 1 second, say `co(11,1);Uw_timers[0] = 91;`co();
  326.   You can then poll this variable at your convenience to determine the time
  327.   expired.  The interrupt decrements the variable by 1 on each tic until
  328.   the count reaches 0, at which time it will remain 0.  The global variables
  329.   `co(11,1);Sys_timers`co(); and `co(11,1);Sound_timer`co(); should not be accessed as these are
  330.   used by UltraWin and its sister product InTUItion.
  331.   
  332. `co(10,1);/// init_clock`co();   `keyword(source,[UW_VID.C]~init_clock);
  333.   This routine takes over the PC timer interrupt and sets the timer rate
  334.     to the desired value.                                              
  335.  
  336. Prototype:
  337. void init_clock( int value );
  338.  
  339. Parameters:
  340. `co(11,1);    uint  value`co();
  341.     The countdown value for the PC timer chip.  0xffff is the standard
  342.     18.2 times per second. 0x7fff would increase the rate by 2, etc.
  343.     
  344. Usage:
  345.     ...
  346.      init_clock(0x3333);                                                 /* speed up by factor of 5 */
  347.  
  348. `co(10,1);/// end_clock`co();   `keyword(source,[UW_VID.C]~end_clock);
  349.   This routine restores the timer interrupt and rate.  Be sure to call this
  350.   function before exiting your program.  `co(11,1);end_video()`co(); will call this for
  351.   you if you forget.
  352.  
  353. Prototype:
  354. void end_clock();
  355.  
  356. Parameters:
  357.  
  358. Usage:
  359.     ...
  360.      end_clock();
  361.     end_mouse();
  362.     end_video();
  363.     exit(0);
  364.   
  365. `co(10,1);/// tone`co();   `keyword(source,[UW_VID.C]~tone);
  366.   This routine sounds the PC speaker at the desired frequency for the 
  367.     desired amount of time measured in timer tics. (91/s).  There is no
  368.     need to turn the sound off, this is automatically handled by the timer
  369.     interrupt.  It is perfectly safe to call tone even if a tone is already
  370.     in progress.  The new frequency and time will override the current
  371.     values.  If you need to turn the speaker off before the time has 
  372.     expired you can call `co(11,1);sound_off();`co();
  373.  
  374. Prototype:
  375. void tone( uint freq, int dur );
  376.  
  377. Parameters:
  378. `co(11,1);    uint  freq`co();
  379.     The desired frequency in hertz or cycles-per-second.   
  380. `co(11,1);    int    dur`co();
  381.     The duration of the tone in clock tics (91-per-second).
  382.  
  383. Usage:
  384.     ...
  385.   if( error )
  386.       tone(1024,9);                                                         /* sound at 1k for 1/10 second */
  387.  
  388. `co(4,7);───────────────────── /// Ctrl-C/Ctrl-Break Control ────────────────────────`co();
  389.   
  390.   UltraWin V2.0 takes over the Ctrl-C and Ctrl-Break handlers and installs
  391.   a dummy interrupt handler.  In this way, Ctrl-C can be used as any other
  392.   control key.  More importantly, your program will not abort without 
  393.   restoring the clock interrupt.  If you need further control over these
  394.   handlers you can modify the ISR's `co(11,1);uw_ctrl_brk();`co(); and `co(11,1);uw_ctrl_c()`co();.
  395.   
  396. `co(4,7);─ End ──────────────────────────────────────────────────────────────────────`co();`sound(1024,10);
  397.